USB Memory Functions4

The memory functions allow USB class drivers to allocate and deallocate memory. Since memory allocation must typically occur at task time, the memory functions will queue the request until task time is available, then allocate the memory and return asynchronously. These functions are the preferred way of specifying memory requirements, because they relieve the class driver from monitoring execution levels when performing memory management functions.

USBAllocMem

The USBAllocMem function allocates a specified amount of memory.



 
OSStatus USBAllocMem(USBPB *pb);

Required fields in the USBPB parameter block for the USBAllocMem function are

--> pbLength: Length of parameter block
--> pbVersion: Parameter block version number
--> usbCompletion: The completion routine
--> usbRefcon: General-purpose value passed back to the completion routine
--> usbReference: A device, interface, or pipe reference which associates the call with a device
--> usbReqCount: Amount of memory required to be allocated
<-- usbActCount: Amount of memory actually allocated
<-- usbBuffer: Memory allocated
--> usbFlags: Should be set to 0

There must be a valid USBReference passed in the usbReference field of the parameter block. If a nil value or a reference that does not match an existing device, interface, or pipe is passed in, the call returns immediately with an unknown device error.

If the device associated with this call is unplugged and its driver removed while this function call is pending, the function will not complete.

The USBAllocMem function returns the following error:

kUSBUnknownDeviceErr -6998 usbReference does not refer to a current device

USBDeallocMem

The USBDeallocMem function deallocates the memory allocated with the USBAllocMem function.



 
OSStatus USBDeallocMem(USBPB *pb);

Required fields in the USBPB parameter block for the USBDeallocMem function are:

--> pbLength: Length of parameter block
--> pbVersion: Parameter block version number
--> usbCompletion: The completion routine
--> usbRefcon: General-purpose value passed back to the completion routine
--> usbReference: A device, interface, or pipe reference which associates the call with a device
<--> usbBuffer: --> previously allocated memory to be deallocated <-- pointer set to nil
--> usbFlags: Should be set to 0

You can pass kUSBNoCallBack as the usbCompletion field parameter to notify the USL that you want the operation to complete immediately if at task time. It is an error to specify no call back, if the current execution level is not task time.

If the usbCompletion field is set to kUSBNoCallBack, the call back mechanism is not invoked. This is useful for finalization routines which need to clean up immediately and can't wait for a callback routine to complete.

There must be a valid USBReference passed in the usbReference field of the parameter block. If a nil value or a reference that does not match an existing device, interface, or pipe is passed in, the call returns immediately with an unknown device error.

If the device associated with this call is unplugged and its driver removed while this function call is pending, the function will not complete.

The USBDeAllocMem function returns the following error:

`kUSBUnknownDeviceErr`	`-6998`	`usbReference` does not refer to a current device
`kUSBCompletionError`	`-6984`	`kUSBNoCallBack` was specified and current execution level is not task time